Lua utility module CustomBar

This module provides functions for creating and managing custom progress bars.

It stores bar definitions and configurations in LevelVars.Engine.CustomBars, enabling seamless state management. Each bar is independently controlled through its associated functions.

Example usage:

local CustomBar = require("Engine.CustomBar")

-- Create a table with all the bar properties
local barData = {
    barName             = "water",
    startValue          = 0,
    maxValue            = 1000,
    objectIdBg          = TEN.Objects.ObjID.CUSTOM_BAR_GRAPHIC,
    spriteIdBg          = 0,
    colorBg             = TEN.Color(255,255,255),
    posBg               = TEN.Vec2(20, 20),
    rotBg               = 0,
    scaleBg             = TEN.Vec2(19.05, 19.1),
    alignModeBg         = TEN.View.AlignMode.CENTER_LEFT,
    scaleModeBg         = TEN.View.ScaleMode.FIT,
    blendModeBg         = TEN.Effects.BlendID.ALPHABLEND,
    objectIdBar         = TEN.Objects.ObjID.CUSTOM_BAR_GRAPHIC,
    spriteIdBar         = 1,
    colorBar            = TEN.Color(255,0,0),
    posBar              = TEN.Vec2(20.15, 20),
    rot                 = 0,
    scaleBar            = TEN.Vec2(18.7, 18.48),
    alignMode           = TEN.View.AlignMode.CENTER_LEFT,
    scaleMode           = TEN.View.ScaleMode.FIT,
    blendMode           = TEN.Effects.BlendID.ALPHABLEND,
    text                = "Water Bar",
    textPos             = TEN.Vec2(20, 15),
    textOptions         = {TEN.Strings.DisplayStringOption.SHADOW,TEN.Strings.DisplayStringOption.CENTER},
    textScale           = 1,
    textColor           = TEN.Color(255,0,0),
    hideText            = false,
    alphaBlendSpeed     = 50,
    blink               = false,
    blinkLimit          = 0.25
}

-- This function creates the bar.
CustomBar.Create(barData)

-- This method gets the bar with name "water" and stores it in variable bar.
local bar = CustomBar.Get("water")
-- This method displays the bar
bar:SetVisibility(true)
-- This method sets the bar value to 1000 over 5 seconds.
bar:SetBarValue(1000,5)

Functions

Create(barData) Creates a custom progress bar with extensive configuration options.
CreatePlayerBar(playerBarData) Creates a bar tied to Players's attributes (Health, Air, Stamina).
CreateEnemyHpBar(enemyBarData) Creates a custom health bar for a specific enemy (like a boss).
SetEnemiesHpGenericBar(enemiesBarData) Creates health bars for all enemies.
Get(barName) The function retrieves an existing bar instance by its unique identifier (barName).
Delete(barName) The function removes a custom bar and its associated data from the system.
SetBarValue(value, time) The function sets the value of a custom bar over a specified time period.
ChangeBarValueOverTimespan(value, time) The function adjusts the bar's value relative to its current or target value over a specified time span.
SetVisibility(visible) The function controls the visibility of a custom bar.
IsVisible() The function checks whether a custom bar is currently visible.
GetValue() The function retrieves the current value of a custom bar.
DeleteAllBars() The function deletes all custom bars.
ShowEnemiesHpGenericBar(value) This function prevents the creation of new health bars for enemies when set to false.
DeleteExistingHpGenericBars() The function deletes all the enemy health bars excluding those created by CustomBar.CreateEnemyHpBar.
SetBackgroundPosition(pos) Sets the custom bar background sprite position.
SetBackgroundRotation(rot) Sets the custom bar background sprite rotation.
SetBackgroundScale(scale) Sets the custom bar background sprite scale.
SetBackgroundSpriteSlot(slot, id) Sets the custom bar background sprite slot and sprite ID.
SetBackgroundAlignMode(alignMode) Sets the custom bar background sprite align mode.
SetBackgroundScaleMode(scaleMode) Sets the custom bar background sprite scale mode.
SetBackgroundBlendMode(blendMode) Sets the custom bar background sprite blend mode.
SetBarPosition(pos) Sets the custom bar sprite position.
SetBarRotation(rot) Sets the custom bar sprite rotation.
SetBarColor(color) Sets the custom bar sprite color.
SetBarScale(scale) Sets the custom bar sprite scale.
SetBarSpriteSlot(slot, id) Sets the custom bar sprite slot and sprite ID.
SetBarAlignMode(alignMode) Sets the custom bar sprite alignment mode.
SetBarScaleMode(scaleMode) Sets the custom bar sprite scale mode.
SetBarBlendMode(blendMode) Sets the custom bar sprite blend mode.

Tables

barData Table setup for creating custom bar.
playerBarData Table setup for creating custom player attribute bar.
enemyBarData Table setup for creating a specific enemy health bar.
enemiesBarData Table setup for creating health bars for all enemies.


Functions

Create(barData)
Creates a custom progress bar with extensive configuration options.

Parameters:

  • barData table The table that contains all the bar data. Refer to table setup for barData.

Returns:

    CustomBar The custombar in its hidden state
CreatePlayerBar(playerBarData)
Creates a bar tied to Players's attributes (Health, Air, Stamina).

Parameters:

  • playerBarData table The table that contains all the player bar data. Refer to table setup for playerBarData.

Returns:

    CustomBar Player attribute bar.
CreateEnemyHpBar(enemyBarData)
Creates a custom health bar for a specific enemy (like a boss). Ensure this function is called before Lara aims at the enemy if using generic enemy HP bars as well. Also be sure to call this function after increasing the HP of the enemy via LUA.

Parameters:

  • enemyBarData table The table that contains all the enemy bar data. Refer to table setup for enemyBarData.

Returns:

    CustomBar Enemy health bar.
SetEnemiesHpGenericBar(enemiesBarData)
Creates health bars for all enemies. A new bar is generated whenever Lara targets an enemy. If the "hide text" option is disabled, the enemy's name (as set in the editor) is displayed. Multiple enemies can share the same name by appending _number to the name in the editor. If adjusting an enemy's max HP, ensure this is done before Lara targets the enemy. To create health bars for specific enemies, use CustomBar.CreateEnemyHpBar, ensuring the bar is created prior to targeting.

Parameters:

  • enemiesBarData table The table that contains all the enemies bar data. Refer to table setup for enemiesBarData.

Returns:

    CustomBar Enemy health bars.
Get(barName)
The function retrieves an existing bar instance by its unique identifier (barName). This function is useful when you need to access or manipulate a bar that has already been created.

Parameters:

  • barName string The unique identifier assigned to the bar when it was created using CustomBar.New
Delete(barName)
The function removes a custom bar and its associated data from the system. It ensures that the bar is no longer tracked or accessible in the LevelVars.Engine.CustomBars.bars table.

Parameters:

  • barName string The name of the custom bar to be deleted.
SetBarValue(value, time)
The function sets the value of a custom bar over a specified time period.

Parameters:

  • value number The new target to which the bar's current value should transition. (Must be a non-negative number; between 0 and the bar's maxValue.
  • time number The time (in seconds) over which the bar's value should transition to the target value.
ChangeBarValueOverTimespan(value, time)
The function adjusts the bar's value relative to its current or target value over a specified time span.

Parameters:

  • value number The relative value to add (positive or negative) to the current bar value.
  • time number The duration (in seconds) over which the change should occur.
SetVisibility(visible)
The function controls the visibility of a custom bar.

Parameters:

  • visible bool true: Makes the bar visible.; false: Hides the bar.
IsVisible()
The function checks whether a custom bar is currently visible.

Returns:

    bool true if the bar is visible and false if it is not.
GetValue()
The function retrieves the current value of a custom bar.

Returns:

    float returns the current value of a custom bar.
DeleteAllBars()
The function deletes all custom bars.
ShowEnemiesHpGenericBar(value)
This function prevents the creation of new health bars for enemies when set to false. However, it does not affect the health bars that have already been created.

Parameters:

  • value bool Specifies whether new health bars for enemies should be created.
DeleteExistingHpGenericBars()
The function deletes all the enemy health bars excluding those created by CustomBar.CreateEnemyHpBar.
SetBackgroundPosition(pos)
Sets the custom bar background sprite position.

Parameters:

  • pos Vec2 X,Y position of the bar's background in screen percent (0-100).
SetBackgroundRotation(rot)
Sets the custom bar background sprite rotation.

Parameters:

  • rot number rotation of the bar's background. sprite (0-360).
SetBackgroundScale(scale)
Sets the custom bar background sprite scale.

Parameters:

  • scale Vec2 X,Y Scaling factor for the bar's background sprite.
SetBackgroundSpriteSlot(slot, id)
Sets the custom bar background sprite slot and sprite ID.

Parameters:

  • slot ObjID Object ID for the bar's background sprite.
  • id number SpriteID from the specified object for the bar's background.
SetBackgroundAlignMode(alignMode)
Sets the custom bar background sprite align mode.

Parameters:

  • alignMode AlignMode Alignment for the bar's background.
SetBackgroundScaleMode(scaleMode)
Sets the custom bar background sprite scale mode.

Parameters:

  • scaleMode ScaleMode Scaling for the bar's background.
SetBackgroundBlendMode(blendMode)
Sets the custom bar background sprite blend mode.

Parameters:

  • blendMode BlendID Blending modes for the bar's background.
SetBarPosition(pos)
Sets the custom bar sprite position.

Parameters:

  • pos Vec2 X,Y position of the bar in screen percent (0-100).
SetBarRotation(rot)
Sets the custom bar sprite rotation.

Parameters:

  • rot number rotation of the bar's sprite (0-360).
SetBarColor(color)
Sets the custom bar sprite color.

Parameters:

  • color Color Color of the bar.
SetBarScale(scale)
Sets the custom bar sprite scale.

Parameters:

  • scale Vec2 X,Y Scaling factor for the bar's sprite.
SetBarSpriteSlot(slot, id)
Sets the custom bar sprite slot and sprite ID.

Parameters:

  • slot ObjID Object ID for the bar sprite.
  • id number SpriteID from the specified object for the bar.
SetBarAlignMode(alignMode)
Sets the custom bar sprite alignment mode.

Parameters:

SetBarScaleMode(scaleMode)
Sets the custom bar sprite scale mode.

Parameters:

SetBarBlendMode(blendMode)
Sets the custom bar sprite blend mode.

Parameters:

  • blendMode BlendID Blending modes for the bar.

Tables

barData
Table setup for creating custom bar.

Fields:

  • barName string Unique identifier for the bar.
  • startValue float Initial value of the bar.
  • maxValue float Maximum value of the bar.
  • objectIdBg ObjID Object ID for the bar's background sprite.
  • spriteIdBg number SpriteID from the specified object for the bar's background.
  • colorBg Color Color of bar's background.
  • posBg Vec2 X,Y position of the bar's background in screen percent (0-100).
  • rotBg float rotation of the bar's background. sprite (0-360).
  • scaleBg Vec2 X,Y Scaling factor for the bar's background sprite.
  • alignModeBg AlignMode Alignment for the bar's background.
  • scaleModeBg ScaleMode Scaling for the bar's background.
  • blendModeBg BlendID Blending modes for the bar's background.
  • objectIdBar ObjID Object ID for the bar sprite.
  • spriteIdBar number SpriteID from the specified object for the bar.
  • colorBar Color Color of the bar.
  • posBar Vec2 X,Y position of the bar in screen percent (0-100).
  • rot float rotation of the bar's sprite (0-360).
  • scaleBar Vec2 X,Y Scaling factor for the bar's sprite.
  • alignMode AlignMode Alignment for the bar.
  • scaleMode ScaleMode Scaling for the bar.
  • blendMode BlendID Blending modes for the bar.
  • text string Text to display on the bar.
  • textPos Vec2 X,Y position of the text.
  • textOptions DisplayStringOption alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT
  • textScale number Scale factor for the text.
  • textColor Color Color of the text.
  • hideText bool Whether to hide the text.
  • alphaBlendSpeed number Speed of alpha blending for bar visibility (0-255).
  • blink bool Whether the bar blinks.
  • blinkLimit number % Limit below which bar starts blinking (0-1).
playerBarData
Table setup for creating custom player attribute bar.

Fields:

  • getActionType number Determines the bar type: 1: Health, 2: Air, 3: Stamina.
  • objectIdBg ObjID Object ID for the bar's background sprite.
  • spriteIdBg number SpriteID from the specified object for the bar's background.
  • colorBg Color Color of bar's background.
  • posBg Vec2 X,Y position of the bar's background in screen percent (0-100).
  • rotBg number rotation of the bar's background. sprite (0-360).
  • scaleBg Vec2 X,Y Scaling factor for the bar's background sprite.
  • alignModeBg AlignMode Alignment for the bar's background.
  • scaleModeBg ScaleMode Scaling for the bar's background.
  • blendModeBg BlendID Blending modes for the bar's background.
  • objectIdBar ObjID Object ID for the bar sprite.
  • spriteIdBar number SpriteID from the specified object for the bar.
  • colorBar Color Color of the bar.
  • posBar Vec2 X,Y position of the bar in screen percent (0-100).
  • rot number rotation of the bar's sprite (0-360).
  • scaleBar Vec2 X,Y Scaling factor for the bar's sprite.
  • alignMode AlignMode Alignment for the bar.
  • scaleMode ScaleMode Scaling for the bar.
  • blendMode BlendID Blending modes for the bar.
  • alphaBlendSpeed number Speed of alpha blending for bar visibility (0-255).
  • showBar bool Option to always show the bar. If set to false, the bars will automatically hide when they stop updating.
  • blink bool Whether the bar blinks.
  • blinkLimit number % Limit below which bar starts blinking (0-1).
enemyBarData
Table setup for creating a specific enemy health bar.

Fields:

  • barName string Unique identifier for the bar.
  • objectIdBg ObjID Object ID for the bar's background sprite.
  • spriteIdBg number SpriteID from the specified object for the bar's background.
  • colorBg Color Color of bar's background.
  • posBg Vec2 X,Y position of the bar's background in screen percent (0-100).
  • rotBg number rotation of the bar's background. sprite (0-360).
  • scaleBg Vec2 X,Y Scaling factor for the bar's background sprite.
  • alignModeBg AlignMode Alignment for the bar's background.
  • scaleModeBg ScaleMode Scaling for the bar's background.
  • blendModeBg BlendID Blending modes for the bar's background.
  • objectIdBar ObjID Object ID for the bar sprite.
  • spriteIdBar number SpriteID from the specified object for the bar.
  • colorBar Color Color of the bar.
  • posBar Vec2 X,Y position of the bar in screen percent (0-100).
  • rot number rotation of the bar's sprite (0-360).
  • scaleBar Vec2 X,Y Scaling factor for the bar's sprite.
  • alignMode AlignMode Alignment for the bar.
  • scaleMode ScaleMode Scaling for the bar.
  • blendMode BlendID Blending modes for the bar.
  • text string Text to display for the enemy.
  • textPos Vec2 X,Y position of the text.
  • textOptions DisplayStringOption alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT
  • textScale number Scale factor for the text.
  • textColor Color Color of the text.
  • hideText bool Whether to hide the text.
  • alphaBlendSpeed number Speed of alpha blending for bar visibility (0-255).
  • object string Enemy name set in Editor for which to create HP for.
  • showBar bool Option to always show the bar whether the enemy is current target or not. Useful for boss health bars.
  • blink bool Whether the bar blinks.
  • blinkLimit number %Limit below which bar starts blinking (0-1).
enemiesBarData
Table setup for creating health bars for all enemies.

Fields:

  • objectIdBg ObjID Object ID for the bar's background sprite.
  • spriteIdBg number SpriteID from the specified object for the bar's background.
  • colorBg Color Color of bar's background.
  • posBg Vec2 X,Y position of the bar's background in screen percent (0-100).
  • rotBg number rotation of the bar's background. sprite (0-360).
  • scaleBg Vec2 X,Y Scaling factor for the bar's background sprite.
  • alignModeBg AlignMode Alignment for the bar's background.
  • scaleModeBg ScaleMode Scaling for the bar's background.
  • blendModeBg BlendID Blending modes for the bar's background.
  • objectIdBar ObjID Object ID for the bar sprite.
  • spriteIdBar number SpriteID from the specified object for the bar.
  • colorBar Color Color of the bar.
  • posBar Vec2 X,Y position of the bar in screen percent (0-100).
  • rot number rotation of the bar's sprite (0-360).
  • scaleBar Vec2 X,Y Scaling factor for the bar's sprite.
  • alignMode AlignMode Alignment for the bar.
  • scaleMode ScaleMode Scaling for the bar.
  • blendMode BlendID Blending modes for the bar.
  • textPos number X position of the text.
  • textOptions DisplayStringOption alignment and effects for the text. Default: None. Please note text is automatically aligned to the LEFT
  • textScale number Scale factor for the text.
  • textColor Color Color of the text.
  • hideText bool Whether to hide the enemy name text.
  • alphaBlendSpeed number Speed of alpha blending for bar visibility (0-255).
  • blink bool Whether the bar blinks.
  • blinkLimit number %Limit below which bar starts blinking (0-1).
generated by TEN-LDoc (a fork of LDoc 1.4.6)